// $Id: string_tokenizer.h,v 1.3 2006-08-22 03:10:19 nicolasw Exp $

#ifndef __STRING_TOKENIZER_H
#define __STRING_TOKENIZER_H

/* Tokenizer para cadenas. Escrito por Rafael Carrascosa para la catedra de
 * Sistemas Operativos, FaMAF, UNC.
 * Eres libre de modificar,utilizar y distribuir este codigo para cualquier 
 * fin siempre y cuando reconozcas mi participacion en su escritura.
 */

/* Ver notas sobre que es un tokenizer, para que sirve y como se usa al
 * final de archivo
 */

typedef struct sstring_tokenizer_t *string_tokenizer_t;

/* Constructor comun y corriente. 
 * str contiene la cadena que se quiere tokenizar.
 * separators es una cadena que se interpreta como un conjunto de caracteres.
 * El conjunto de caracteres en separators se usa para determinar donde 
 * empiezan y donde termian las "palabras"(tokens) en str.
 * En caso de error devuelve NULL.
 * Esta funcion inicializa el iterador asique esta listo para que se use
 * string_tokenizer_get inmediatamente(a menos que str=="").
 * separators == "" es valido.
 * Ni esta funcion ni las otras de este TAD modifican str o separators(como se
 * indica en el prototipo de la funcion).
 */
string_tokenizer_t string_tokenizer_create(const char *str,
					   const char *separators);

/* Destructor comun y corriente. Devuelve NULL en caso de exito o
 * abort() en caso de fallo.
 */
string_tokenizer_t string_tokenizer_destroy(string_tokenizer_t st);

/* Devuelve el elemento actual del iterador y luego modifica "st" para que 
 * el iterador este apuntando sobre el elemento siguiente. Bajo ningun 
 * concepto se debe llamar a esta funcion si string_tokenizer_is_end(st)!=0.
 */
char * string_tokenizer_next(string_tokenizer_t st);

/* Devuelve un entero no nulo en caso de no haber mas elementos sobre los
 * cuales iterar. En caso contrario devuelve 0.
 */
int string_tokenizer_is_end(const string_tokenizer_t st);


/*
 * Que es un tokenizer? Token significa en ingles algo asi como
 * "pedacito". Un tokenizer es un programa que parte algo en
 * "pedacitos" o tokens. En nuestro caso es un tokenizer de cadenas,
 * lo que significa que parte (corta, separa, individualiza)
 * subcadenas de una cadena mayor.
 * Un ejemplo: "Habia mucha gente" puede ser tokenizado en "Habia"," ",
 * "mucha"," " y "gente". 
 * Que requiere este TAD? Que le digan en DONDE tiene que cortar.
 * Digamos, en el ejemplo anterior los tokens se forman partiendo la cadena
 * original con el separador " ". Este tokenizer permite partir por mas de un
 * separador. Entonces esa misma cadena con separadores " a" produce los 
 * tokens "H","a","bi","a"," ","much","a"," " y "gente".
 * Ademas de ser tokenizer, a este TAD se le ha agregado un iterador. Un 
 * iterador es una forma sofisticada(lease "con clase") de recorrer los 
 * elementos de un conjunto o de una lista o arreglo.
 * Una funcion _next() permite ir avanzando por los elementos del mismo sin
 * repetir. En nuestro caso: string_tokenizer_next nos da el token actual y
 * avanza hacia el siguiente.
 */


#endif /* __STRING_TOKENIZER_H */
